<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>CoUnit documentation</title>
<meta content="DocBook XSL Stylesheets V1.71.1" name="generator">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="article" lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title">
<a name="N10002"></a>CoUnit documentation</h2>
</div>
<div>
<div class="authorgroup">
<div class="author">
<h3 class="author">
<span class="firstname">Nico</span> <span class="surname">Verwer</span>
</h3>
<code class="email">&lt;<a href="mailto:nverwer@be-value.nl">nverwer@be-value.nl</a>&gt;</code>
</div>
<div class="author">
<h3 class="author">
<span class="firstname">Jan Willem</span> <span class="surname">Boer</span>
</h3>
<code class="email">&lt;<a href="mailto:janwillem@jwenr.nl">janwillem@jwenr.nl</a>&gt;</code>
</div>
</div>
</div>
</div>
<hr>
</div>
<div class="toc">
<p>
<b>Table of Contents</b>
</p>
<dl>
<dt>
<span class="sect1"><a href="#about">About CoUnit</a></span>
</dt>
<dt>
<span class="sect1"><a href="#usingCoUnit">Using CoUnit</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="sect2"><a href="#preparingCoUnit">Preparing CoUnit</a></span>
</dt>
<dt>
<span class="sect2"><a href="#simpleTest">Defining a simple test</a></span>
</dt>
<dt>
<span class="sect2"><a href="#alternativeTest">Including input and expected output in testcase.xml</a></span>
</dt>
<dt>
<span class="sect2"><a href="#transformerTests">Test a transformer</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="sect1"><a href="#testSuite">The testsuite.xml file</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="sect2"><a href="#testsuite">testsuite</a></span>
</dt>
<dt>
<span class="sect2"><a href="#testcase">testcase</a></span>
</dt>
<dt>
<span class="sect2"><a href="#xslt">xslt</a></span>
</dt>
<dt>
<span class="sect2"><a href="#stx">stx</a></span>
</dt>
<dt>
<span class="sect2"><a href="#transformer">transformer</a></span>
</dt>
<dt>
<span class="sect2"><a href="#outputFilter">output-filter</a></span>
</dt>
<dt>
<span class="sect2"><a href="#input-files">Additional input files</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="sect1"><a href="#counitComponents">CoUnit components and options</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="sect2"><a href="#mount-table">mount-table</a></span>
</dt>
<dt>
<span class="sect2"><a href="#find-testsuite">find-testsuite</a></span>
</dt>
<dt>
<span class="sect2"><a href="#prepare-xslt-stx">prepare-xslt and prepare-stx</a></span>
</dt>
<dt>
<span class="sect2"><a href="#prepare-transformer">prepare-transformer</a></span>
</dt>
<dt>
<span class="sect2"><a href="#new">(new transformation test types)</a></span>
</dt>
<dt>
<span class="sect2"><a href="#prepare-filter">prepare-filter</a></span>
</dt>
<dt>
<span class="sect2"><a href="#write-source">write-source</a></span>
</dt>
<dt>
<span class="sect2"><a href="#cinclude">cinclude</a></span>
</dt>
<dt>
<span class="sect2"><a href="#cleanup">prepare-cleanup and cleanup</a></span>
</dt>
<dt>
<span class="sect2"><a href="#include-expected-output">include-expected-output</a></span>
</dt>
<dt>
<span class="sect2"><a href="#remove-whitespace">remove-whitespace</a></span>
</dt>
<dt>
<span class="sect2"><a href="#evaluate-results">evaluate-results</a></span>
</dt>
<dt>
<span class="sect2"><a href="#format-results">format-results</a></span>
</dt>
<dt>
<span class="sect2"><a href="#html-report">html-report (optional)</a></span>
</dt>
</dl>
</dd>
</dl>
</div>
<div class="sect1" lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="about"></a>About CoUnit</h2>
</div>
</div>
</div>
<p> CoUnit is a unit test framework for <a href="http://www.apache.org/cocoon" target="_top">Apache
        Cocoon</a>. It has been developed on Cocoon 2.1.10, but should work on Cocoon versions
      from 2.1.8. CoUnit makes it possible to define and execute unit and regression tests for xsl
      stylesheets, Cocoon transformers and other Cocoon components. Tests for CoUnit 1.0, which was
      presented at the Cocoon GetTogether 2004, are not compatible with tests for CoUnit 2.0. CoUnit
      has been developed by Nico Verwer <code class="email">&lt;<a href="mailto:nverwer@gmail.com">nverwer@gmail.com</a>&gt;</code> and Jan Willem Boer
        <code class="email">&lt;<a href="mailto:janwillem@jwenr.nl">janwillem@jwenr.nl</a>&gt;</code>, and is released into the public domain. This document
      provides the basic documentation for using and extending CoUnit. It has been updated <a href="#lastmodified">18-9-2007</a>.</p>
</div>
<div class="sect1" lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="usingCoUnit"></a>Using CoUnit</h2>
</div>
</div>
</div>
<div class="sect2" lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="preparingCoUnit"></a>Preparing CoUnit</h3>
</div>
</div>
</div>
<p> To use CoUnit in your project or application, add the counit application directory to
        the Cocoon mount table with the uri-prefix "counit" (you may use a different uri-prefix).
        Alternatively, copy the counit directory ("counit2.0") to your webapp and rename it to
        "counit".</p>
<p>In order to find Cocoon applications that must be tested, CoUnit has its own
        mount-table. In order to test an application, you add it to the counit mount table. The
        counit mount table is located in the directory directly above the counit directory. This
        makes it easy to update counit to a new version without affecting your counit mount table.
        The mount table file name is counit-mount-table.xml. To add an application to the mount
        table, add a mount element with the attributes <code class="constant">uri-prefix</code> and
          <code class="constant">src</code>. The <code class="constant">src</code> attribute is the absolute path to
        the directory containing the sitemap. Unlike normal Cocoon mount-tables, it must not point
        to a sitemap directly. The <code class="constant">uri-prefix</code> attribute can be anything you
        like, and is the identifier with which the tests can be executed. <pre class="programlisting">&lt;mount-table&gt;
  &lt;mount uri-prefix="MyAppToTest" 
    src="file:///C:/Projects/MyProject/build/webapp/"/&gt;
&lt;/mount-table&gt;</pre> The entries in the mount table must always have a slash as the
        last character in the <code class="constant">src</code> attribute. </p>
<p> Now you should be able to run counit by pointing your webbrowser to
          <code class="uri">http://server:port/counit/report/MyUriPrefix/</code>. It will show an empty document
        because no tests have been defined yet. </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="simpleTest"></a>Defining a simple test</h3>
</div>
</div>
</div>
<p> In this case, we assume we want to test an xsl stylesheet: <pre class="programlisting">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
  &lt;xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
    version="1.0"&gt;
  &lt;xsl:param name="to"/&gt;

  &lt;xsl:template match="to"&gt;
    &lt;xsl:value-of select="$to"/&gt;
  &lt;/xsl:template&gt;

  &lt;xsl:template match="@*|node()"&gt;
    &lt;xsl:copy&gt;
      &lt;xsl:apply-templates select="@*|node()"/&gt;
    &lt;/xsl:copy&gt;
  &lt;/xsl:template&gt;
&lt;/xsl:stylesheet&gt;</pre> The stylesheet receives a parameter <code class="constant">to</code>
        and replaces every element <code class="constant">&lt;to&gt;</code> by the value of the
        parameter <code class="constant">to</code>. We assume this stylesheet resides in the application
        directory and has the name <code class="uri">greeting.xsl</code>.</p>
<p> The tests will be organized in a directory called <code class="constant">.counit</code>, which
        is located in the application directory. Create a new directory
        "<code class="constant">.counit</code>" in the application directory (where the sitemap.xmap
        resides). On Windows, this can only be done by using the <span><strong class="command">mkdir</strong></span> command
        from a command window. </p>
<p> A test consists of three parts: <div class="itemizedlist">
<ul type="disc">
<li>
<p>an xml input document</p>
</li>
<li>
<p>an expected xml output document</p>
</li>
<li>
<p>the definition of the test</p>
</li>
</ul>
</div>
      
</p>
<p> In our example, the xml input document is a small xml fragment that is the input to the
        component (in this case the xsl stylesheet) that we want to test. <pre class="programlisting">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;greeting&gt;Hello &lt;to/&gt;, how are you?&lt;/greeting&gt;</pre> Save this file in the .counit
        directory with the name 01-greeting-input.xml. </p>
<p> Next, counit needs the expected output document. We will pass the parameter "world" to
        the transformation, so the expected output would be as follows. <pre class="programlisting">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;greeting&gt;Hello world, how are you?&lt;/greeting&gt;</pre> Save this file in the .counit
        directory with the name 01-greeting-output.xml. </p>
<p> To finish the test, add the test to the testsuite. The testsuite is an xml file which
        describes a related set of tests. When testing the application, counit will automatically
        find the testsuite.xml file and execute all the tests described in the testsuite file.
        Create a file called testsuite.xml in the .counit directory. The testsuite file has an
        element <code class="constant">testsuite</code> as root element. A <code class="constant">testsuite</code> can
        contain other <code class="constant">testsuite</code> elements or <code class="constant">testcase</code>
        elements. The <code class="constant">testcase</code> element has an <code class="constant">id</code>
        attribute, an <code class="constant">input</code> and an <code class="constant">expect</code> attribute in
        which the test files can be referenced. The <code class="constant">testcase</code> element contains
        the transformation details which define which transformation will be executed on the input
        file. <pre class="programlisting">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;testsuite&gt;
  &lt;testcase id="01-greeting" input="01-greeting-input.xml" 
    expect="01-greeting-output.xml" description="A sample test"&gt;
    &lt;xslt src="greeting.xsl"&gt;
      &lt;parameter name="to" value="world"/&gt;
    &lt;/xslt&gt;
  &lt;/testcase&gt;
&lt;/testsuite&gt;</pre> In the example we define the transformation as an xslt
        transformation with the stylesheet greeting.xsl. As parameter we define
        <code class="constant">to</code> to be "world". A good practice is to use the
        <code class="constant">description</code> attribute for an adequate description of the test. The
        contents of the <code class="constant">description</code> attribute will be shown if the test fails,
        which can be very convenient to locate the problem. </p>
<p> Now you can browse to the counit test suite again, and observe that your test is
        succesful. You should see a page similar to the one in the example below. If one or more
        tests fail, detailed diff information is given. To re-test this testcase, click on the name
        of the testcase. In a real-world test-driven situation, you would have written the test
        first, watched it fail, and then written the stylesheet.</p>
<p>In a textual context whitespace differences are often not relevant. If the testcase
        attribute <code class="constant">ignore-whitespace</code>, is set to <code class="constant">true</code> (which
        is the default), the whitespace in the output and expected output documents will be
        normalized. If this gives unwanted side-effects, use
        <code class="constant">ignore-whitespace="false"</code>.</p>
<div class="mediaobject">
<img src="images/counit-html-output.png"></div>
</div>
<div class="sect2" lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="alternativeTest"></a>Including input and expected output in testcase.xml</h3>
</div>
</div>
</div>
<p>An alternative to this approach is to include the test input and expected output in the
        testsuite.xml file. For small tests this is more efficient than the separate files approach.
        The input and expected output are included directly in the testcase in the
        <code class="constant">input</code> and <code class="constant">expect</code> elements. <pre class="programlisting">&lt;testcase id="03-reverse" ignore-whitespace="true"&gt;
  &lt;input&gt;
    &lt;text-to-reverse&gt; 
      The text in this element 
      &lt;embedded-element/&gt; 
      will be reversed.
    &lt;/text-to-reverse&gt;
  &lt;/input&gt;
  &lt;expect&gt;
    &lt;text-to-reverse&gt; 
      tnemele siht ni txet ehT 
      &lt;embedded-element/&gt; 
      .desrever eb lliw
    &lt;/text-to-reverse&gt;
  &lt;/expect&gt;
  &lt;xslt src="reverse.xsl"/&gt;
&lt;/testcase&gt;</pre> The <code class="constant">input</code> and <code class="constant">expect</code>
        elements can only contain one root element. </p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>This mechanism does not work for XML that can be interpreted by a Cocoon component,
          like the cinclude transformer. This is because the cinclude and sourcewriting
          transformers are used in the testing process. If the XML in <code class="constant">input</code> or
            <code class="constant">expect</code> elements includes instructions for these components, they
          will be interpreted and executed by the test pipeline and most likely result in strange
          error messages. To test cinclude and sourcewriting XML instructions, use the external
          files for input and expected output. </p>
<p>Alternatively, if the expected output contains cocoon instructions, and the input
          doesn't, you could use a filter stylesheet to transform cinclude- and sourcewriting
          elements in the output to other elements. See the <a href="#outputFilter">output-filter</a> option about the use of output filtering stylesheets. You could
          use the following filtering stylesheet: <pre class="programlisting">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:ci="http://apache.org/cocoon/include/1.0" 
  xmlns:filtered="http://cocoondev.org/counit/filtered"
  xmlns:source="http://apache.org/cocoon/source/1.0"
  version="1.0"&gt;

  &lt;xsl:template match="ci:*|source:*"&gt; 
    &lt;xsl:element name="filtered:{local-name()}" 
      namespace="http://cocoondev.org/counit/filtered"&gt;
      &lt;xsl:attribute name="filtered:ns"&gt;
        &lt;xsl:value-of select="namespace-uri()"/&gt;
      &lt;/xsl:attribute&gt;
      &lt;xsl:apply-templates select="@*|node()"/&gt;
    &lt;/xsl:element&gt;
  &lt;/xsl:template&gt;
  
  &lt;!-- copy everything else --&gt;
  &lt;xsl:template match="node()|@*"&gt;
    &lt;xsl:copy&gt;
      &lt;xsl:copy-of select="@*"/&gt;
      &lt;xsl:apply-templates select="node()"/&gt;
    &lt;/xsl:copy&gt;
  &lt;/xsl:template&gt;

&lt;/xsl:stylesheet&gt;</pre> This stylesheet eliminates the problematic namespaces, but
          preserves the information about them. Using this stylesheet, the expected output can be
          stripped of cinclude and sourcewriting tags. For example: <pre class="programlisting">&lt;testcase id="..." description="..."&gt;
  &lt;input&gt;
    &lt;recipe-step name="teststep"&gt;
      &lt;pipeline file="pipe.xsl"/&gt;
      &lt;transform type="xslt" file="create.xsl"/&gt;
    &lt;/recipe-step&gt;
  &lt;/input&gt;
  &lt;output-filter src="filter-cocoon-instructions.xsl"/&gt;
  &lt;expect&gt;
    &lt;recipe-step name="teststep"&gt;
      &lt;pipeline file="pipe.xsl"&gt;
        &lt;filtered:include 
          filtered:ns="http://apache.org/cocoon/include/1.0" 
          src="teststep/pipe.xsl"/&gt;
      &lt;/pipeline&gt;
      &lt;transform type="xslt" file="create.xsl"/&gt;
    &lt;/recipe-step&gt;
  &lt;/expect&gt;
  &lt;xslt src="some_stylesheet.xsl"/&gt;
&lt;/testcase&gt;</pre>
        
</p>
</div>
</div>
<div class="sect2" lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="transformerTests"></a>Test a transformer</h3>
</div>
</div>
</div>
<p>To test a transformer, the transformer must have been compiled into the Cocoon
        distribution in which CoUnit is running. As an example, we will write a test for the 
        <a href="http://code.google.com/p/cocooncomponents/" target="_top">multifragment transformer</a>. </p>
<p> A transformer can be tested by including a <code class="constant">transformer</code> element in
        the <code class="constant">testcase</code>. The <code class="constant">src</code> attribute must be set to the
        full java classname of the transformer. In this case we want to test the multifragment transformer,
        so the <code class="constant">src</code> attribute would be
          <code class="constant">org.apache.cocoon.transformation.MultiFragmentTraxTransformer</code>. </p>
<p>If the transformer needs configuration, this included in the <code class="constant">configuration</code> element.
        Some transformers use attributes that are passed in the <code class="constant">map:transform</code>,
        usually <code class="constant">src</code>. These attributes must be given as <code class="constant">attribute</code>
        elements in the <code class="constant">transformer</code> element.
        Parameters that would normally be declared within the <code class="constant">map:transform</code> element 
        should be included in the <code class="constant">transformer</code> element.
        The input and expected output settings can be configured in the same way as the xslt testcases.
<pre class="programlisting">
&lt;transformer src="org.apache.cocoon.transformation.MultiFragmentTraxTransformer"&gt;
  &lt;configuration&gt;
    &lt;use-request-parameters&gt;false&lt;/use-request-parameters&gt;
    &lt;use-session-parameters&gt;false&lt;/use-session-parameters&gt;
    &lt;use-cookie-parameters&gt;false&lt;/use-cookie-parameters&gt;
    &lt;xslt-processor-role&gt;xalan&lt;/xslt-processor-role&gt;
    &lt;check-includes&gt;true&lt;/check-includes&gt;
  &lt;/configuration&gt;
  &lt;attribute name="src" file="multifragment/01-stylesheet.xslt"/&gt;
  &lt;parameter name="fragment.element" value="b"/&gt;
&lt;/transformer&gt;
</pre>
        The <code class="constant">attribute</code> element can have either a <code class="constant">value</code> or
        <code class="constant">file</code> attribute.
        A <code class="constant">value</code> attribute is passed literally as the value of the named attribute.
        A <code class="constant">file</code> attribute is turned into a <code class="constant">file:</code> URI,
        pointing to a file relative to the <code class="constant">.counit</code> directory.
      </p>
</div>
</div>
<div class="sect1" lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="testSuite"></a>The testsuite.xml file</h2>
</div>
</div>
</div>
<div class="sect2" lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="testsuite"></a>testsuite</h3>
</div>
</div>
</div>
<p> The testsuite.xml file has one root element, the <code class="constant">testsuite</code>
        element. This element may contain other <code class="constant">testsuite</code> elements or
          <code class="constant">testcase</code> elements. </p>
<p>With the optional <code class="constant">id</code> attribute the testsuite can be given an id to
        identify the testsuite in the output. If no id is provided, the full path will serve as the
        id.</p>
<p>The element can also be used to include other testsuite.xml files. This makes it easy to
        create your tests in a modular way. The <code class="constant">src</code> attribute should contain
        the path to the other application to test, relative to this testsuite (= a directory with a
        .counit directory which contains the testsuite.xml file to mount). <pre class="programlisting">&lt;testsuite&gt;
  &lt;testsuite id="HelloWorld"&gt;
    &lt;testcase ...
    ... /testcase&gt;
  &lt;/testsuite&gt;
  &lt;!-- included testsuite from /HelloWorld/ByeWorld/ --&gt;
  &lt;testsuite src="ByeWorld/"/&gt;
&lt;/testsuite&gt;</pre>
      
</p>
</div>
<div class="sect2" lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="testcase"></a>testcase</h3>
</div>
</div>
</div>
<p>The <code class="constant">testcase</code> element is a child element of
        <code class="constant">testsuite</code>. A testcase defines a single unit test. The
        <code class="constant">id</code> attribute is used to identify this unit test. The
          <code class="constant">description</code> attribute can be used to provide a more verbose
        identifier to this test and can be very useful to find out what is wrong when a test fails.</p>
<p>The input xml for the test is defined in the <code class="constant">input</code> attribute or in
        the <code class="constant">input</code> element. The attribute points to the location (relative to
        the testsuite.xml file) where the file can be found which contains the input; the element
        contains the input itself (the input xml is inline). In the latter case it is not possible
        to use xml which serves as instructions for Cocoon components like the cinclude and the
        sourcewriting transformers (and possible more in the future), because these instructions
        will be interpreted and executed by the CoUnit pipelines. To use these instructions as test
        input, use the <code class="constant">input</code> attribute instead.</p>
<p> The expected output xml is defined in the same way: either by the
        <code class="constant">expect</code> attribute or by the <code class="constant">expect</code> element. The
        same possibilities and restrictions apply. </p>
<p> Default any any whitespace differences are ignored when comparing the expected and
        received output. Set the <code class="constant">ignore-whitespace</code> attribute to
        <code class="constant">false</code> to achieve this. The default is <code class="constant">true</code>.</p>
<p>Which transformation will be applied to the input document is defined by one of the
        transformation elements. Currently available are <code class="constant">xslt</code>,
        <code class="constant">stx</code> and <code class="constant">transformer</code>. <pre class="programlisting">&lt;testcase id="01-reverse" ignore-whitespace="true" 
  description="Each text should be reversed seperately"&gt;
  &lt;input&gt;
    &lt;root-element&gt; 
      The text in this element 
      &lt;embedded-element/&gt; 
      will be reversed.
    &lt;/root-element&gt;
  &lt;/input&gt;
  &lt;expect&gt;
    &lt;root-element&gt; 
      tnemele siht ni txet ehT 
      &lt;embedded-element/&gt; 
      .desrever eb lliw
    &lt;/root-element&gt;
  &lt;/expect&gt;
  [...]
&lt;/testcase&gt;

&lt;testcase id="02-testCInclude" input="cinclude/input.xml" 
  expect="cinclude/expect.xml"
  description="cincludes should not be included in external test input"&gt; 
  [...]
&lt;/testcase&gt;</pre>
      
</p>
</div>
<div class="sect2" lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="xslt"></a>xslt</h3>
</div>
</div>
</div>
<p>The <code class="constant">xslt</code> element is a child element of
        <code class="constant">testcase</code> and defines that an XSL transformation will be applied to the
        input document of the testcase.</p>
<p>The <code class="constant">src</code> attribute points to the XSL stylesheet to be applied. The
        path is relative to the root of the application (NOT to the testsuite.xml file).</p>
<p>Parameters used as input for the XSL transformation can be provided in this element as
          <code class="constant">parameter</code> elements, which should have a <code class="constant">name</code> and
          <code class="constant">value</code> attribute. <pre class="programlisting">&lt;testcase [...]&gt;
  &lt;xslt src="greeting.xsl"&gt;
    &lt;parameter name="to" value="test"/&gt;
  &lt;/xslt&gt;
&lt;/testcase&gt;</pre>
      
</p>
</div>
<div class="sect2" lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="stx"></a>stx</h3>
</div>
</div>
</div>
<p>The <code class="constant">stx</code> element is a child element of <code class="constant">testcase</code>
        and defines that an STX transformation will be applied to the input document of the
        testcase.</p>
<p>The <code class="constant">src</code> attribute points to the STX stylesheet to be applied. The
        path is relative to the root of the application (NOT to the testsuite.xml file).</p>
<p>Parameters used as input for the STX transformation can be provided in this element as
          <code class="constant">parameter</code> elements, which should have a <code class="constant">name</code> and
          <code class="constant">value</code> attribute. <pre class="programlisting">&lt;testcase [...]&gt;
  &lt;stx src="transform.stx"&gt;
    &lt;parameter name="param" value="hello"/&gt;
  &lt;/stx&gt;
&lt;/testcase&gt;</pre>
      
</p>
</div>
<div class="sect2" lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="transformer"></a>transformer</h3>
</div>
</div>
</div>
<p>The <code class="constant">transformer</code> element is a child element of
        <code class="constant">testcase</code> and defines that a custom transformation will be applied to
        the input document of the testcase.</p>
<p>The <code class="constant">src</code> attribute should contain the fully qualified class name of
        the custom transformer. This transformer should have been compiled into the Cocoon
        distribution which CoUnit is running on, otherwise you will receive an error message
        containing the classname as output.</p>
<p>Any configuration, which would appear in the map:components section of the sitemap when
        declaring the transformer component, should be included in the
        <code class="constant">configuration</code> child element.</p>
<p>If the <code class="constant">map:transform</code> element needs to have arguments (usually <code class="constant">src</code>),
      they can be provided as <code class="constant">attribute</code> child elements.
      An <code class="constant">attribute</code> element has a <code class="constant">name</code> attribute, and either a
      <code class="constant">value</code> attribute, with a literal value, or a
      <code class="constant">file</code> attribute, pointing to a file in the <code class="constant">.counit</code> directory.
      A <code class="constant">file</code> attribute is transformed into a <code class="constant">file:</code> URI.
      </p>
<p>Any runtime parameters, which would appear as map:parameter in the map:transform element
        in the sitemap, should be included in <code class="constant">parameter</code> child elements.
        <pre class="programlisting">&lt;testcase [...]&gt;
  &lt;transformer 
    src="org.apache.cocoon.transformation.ReplaceByRegExpTransformer"&gt;
    &lt;configuration&gt;
      &lt;case-insensitive&gt;true&lt;/case-insensitive&gt;
    &lt;/configuration&gt;
    &lt;parameter name="regexp" value="[a-z]+[0-9]+"/&gt;
    &lt;parameter name="replacement" value="(censored)"/&gt;
  &lt;/transformer&gt;
&lt;/testcase&gt;</pre>
      
</p>
</div>
<div class="sect2" lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="outputFilter"></a>output-filter</h3>
</div>
</div>
</div>
<p>An output document may contain XML that is not interesting to the testcase. It can also
        contain dynamic content that changes with every call (for example a timestamp). This would
        make it impossible to make up a decent expected output to compare the results with. For
        these cases the output can be filtered with the <code class="constant">output-filter</code> element,
        which is a child element of the <code class="constant">testcase</code> element. The
        <code class="constant">src</code> attribute should point to a stylesheet which filters the output.
        The location in <code class="constant">src</code> is relative to the testsuite.xml file. <pre class="programlisting">&lt;testcase id="05-filter-output" description="Filter output"&gt;
  &lt;input&gt;
    ...
  &lt;/input&gt;
  &lt;output-filter src="filter-timestamp.xsl"/&gt;
  &lt;expect&gt;
    ...
  &lt;/expect&gt;
  ...</pre>
      
</p>
<p>The stylesheet which does the filtering can be something like: <pre class="programlisting">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;xsl:stylesheet  xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"&gt;

  &lt;xsl:template match="@timestamp" 
    &lt;!-- remove --&gt;
  &lt;/xsl:template&gt;

  &lt;xsl:template match="@*|node()"&gt;
  	&lt;xsl:copy&gt;
      &lt;xsl:apply-templates select="@*|node()"/&gt;
  	&lt;/xsl:copy&gt;
  &lt;/xsl:template&gt;
&lt;/xsl:stylesheet&gt;
</pre>
      
</p>
<p> For simple filters like exclusions and inclusions, the built-in filter generator can be
        used. In this case, the <code class="constant">src</code> attribute should be absent. First a default
        action should be provided in the <code class="constant">action</code> attribute. Actions can be
          <code class="constant">remove-all</code> and <code class="constant">preserve-all</code>. The first will
        result in recursively removing all elements down the tree, the second in recursively copying
        all elements down the tree. When an <code class="constant">output-filter</code> element is provided
        in the testcase, without an <code class="constant">action</code> attribute, the default action value
        is <code class="constant">remove-all</code>.</p>
<p>Next, the recursive processing mode can be switched by defining
        <code class="constant">preserve</code> and <code class="constant">remove</code> elements in the
          <code class="constant">output-filter</code> element. Both elements have a
        <code class="constant">select</code> attribute, which should contain an expression that matches the
        elements from which the mode will be switched to preserve-all or remove-all. </p>
<p> If elements are removed, this can result in an invalid document, because the output
        should have one and only one root element. To circumvent this, use the
          <code class="constant">use-root-element</code> attribute. The value of this attribute will be used
        as root element for the document. </p>
<p> Special care is needed when using namespace prefixes in the <code class="constant">select</code>
        attributes of the <code class="constant">preserve</code> and <code class="constant">remove</code> elements.
        Under the hood a filter stylesheet is generated, which doesn't include the proper namespace
        declarations by default. To use a namespace prefix in the filter, the prefix should be
        declared by adding an attribute to the <code class="constant">output-filter</code> element. The local
        name of this attribute should be <code class="constant">include-namespace</code>, the prefix to the
        attribute should be the namespace prefix to include. Alternatively use the
        <code class="code">name()</code> construction:
          <code class="code">&lt;preserve select="*[name()='prefix:element']"/&gt;</code>. An example of a
        filter that removes elements and attributes from the output, and needs a container
        root-element: <pre class="programlisting">&lt;testcase id="06-filter-output" description="Filter output" 
          xmlns:sense="sensical" xmlns:nonsense="nonsensical"&gt;
  &lt;input&gt;
    &lt;nonsense:element&gt;
      &lt;nonsense:boring&gt;
        &lt;sense:texts&gt;
          &lt;text boring-attribute="true"&gt;This is some text to replace.&lt;/text&gt;
          &lt;nonsense:boring/&gt;
        &lt;/sense:texts&gt;
        &lt;sense:texts&gt;
          &lt;text&gt;This is text not meant to be replaced.&lt;/text&gt;
        &lt;/sense:texts&gt;
      &lt;/nonsense:boring&gt;
    &lt;/nonsense:element&gt;
  &lt;/input&gt;
  &lt;!-- 
    all elements are copied to the result tree, only the text 
    is modified. We are only interested in the modifications, 
    so remove the copied elements and attributes.
   --&gt;
  &lt;output-filter use-root-element="blah" 
    sense:include-namespace="true" 
    nonsense:include-namespace="true"&gt;
    &lt;preserve select="sense:texts"/&gt;
    &lt;remove select="sense:texts/nonsense:boring"/&gt;
    &lt;remove select="@boring-attribute"/&gt;
  &lt;/output-filter&gt;
  &lt;expect&gt;
    &lt;blah&gt;
      &lt;sense:texts&gt;
        &lt;text&gt;This was an awesome text to replace.&lt;/text&gt;
      &lt;/sense:texts&gt;
      &lt;sense:texts&gt;
        &lt;text&gt;This is text not meant to be replaced.&lt;/text&gt;
      &lt;/sense:texts&gt;
    &lt;/blah&gt;
    &lt;/expect&gt;</pre> Note the use of the
        <code class="constant">sense:include-namespace="true"</code> attribute in the above example to make
        sure the namespace can be used in the filter. An example of a filter that uses the
          <code class="constant">preserve-all</code> mode to begin with: <pre class="programlisting">&lt;testcase id="07-filter-output" description="Filter output"&gt;
  &lt;input&gt;
    &lt;nonsense:element xmlns:nonsense="nonsensical"&gt;
      &lt;nonsense:boring&gt;
        &lt;sense:texts xmlns:sense="sensical"&gt;
          &lt;text&gt;This is some text to replace.&lt;/text&gt;
        &lt;/sense:texts&gt;
        &lt;sense:texts xmlns:sense="sensical"&gt;
          &lt;text&gt;This is text not meant to be replaced.&lt;/text&gt;
        &lt;/sense:texts&gt;
      &lt;/nonsense:boring&gt;
    &lt;/nonsense:element&gt;
  &lt;/input&gt;
  &lt;output-filter action="preserve-all"&gt;
    &lt;remove select="text"/&gt;
  &lt;/output-filter&gt;
  &lt;expect&gt;
    &lt;nonsense:element xmlns:nonsense="nonsensical"&gt;
      &lt;nonsense:boring&gt;
        &lt;sense:texts xmlns:sense="sensical"&gt;
        &lt;/sense:texts&gt;
        &lt;sense:texts xmlns:sense="sensical"&gt;
        &lt;/sense:texts&gt;
      &lt;/nonsense:boring&gt;
    &lt;/nonsense:element&gt;
  &lt;/expect&gt;
  [...] </pre>
      
</p>
</div>
<div class="sect2" lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="input-files"></a>Additional input files</h3>
</div>
</div>
</div>
<p> Sometimes it is necessary to access additional input files from the xsl stylesheet,
        which is not available at the moment of the test. These files can be included in the .counit
        directory and accessed by using the counit-file:// protocol. </p>
<p>When CoUnit encounters the <code class="constant">counit-file://</code> prefix in a parameter
        value in the <code class="constant">xsl</code> tag or any attribute in the <code class="constant">input</code>
        tag, it will resolve the path and make the file accessible to the stylesheet. For example,
        consider a stylesheet that includes files and is instructed by a special tag. <pre class="programlisting">&lt;testcase id="01-include"
      description="External files should be included in the content"&gt;
      &lt;input&gt;
        &lt;doc&gt;
          &lt;include&gt;
            &lt;file href="counit-file://include/a-document.xml"/&gt;
          &lt;/include&gt;
        &lt;/doc&gt;
      &lt;/input&gt;
      &lt;expect&gt;
        &lt;doc&gt;
          &lt;contents-of-document/&gt;
        &lt;/doc&gt;
      &lt;/expect&gt;
      &lt;xslt src="include.xsl"/&gt;
    &lt;/testcase&gt;</pre> The path will be resolved to the directory
        include/a-document.xml relative to the testcase.xml file. The same can be done with xsl
        parameters.</p>
</div>
</div>
<div class="sect1" lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="counitComponents"></a>CoUnit components and options</h2>
</div>
</div>
</div>
<p> The CoUnit entrypoints are the test/**- and report/**-patterned matches in the main
      CoUnit sitemap. They produce the testdata, the latter in a nice HTMLized format. </p>
<p>The main test pipeline which is the source for the entry points, is the **-patterned
      match. Here the testcase.xml is read and the testcases prepared. The test pipeline consists of
      several steps, which will be explained below. If something goes wrong, the test pipeline can
      be debugged on step level. The pipeline can be "paused" on every step. This is done by using
      the cocoon-view url parameter. For example
        <code class="uri">http://127.0.0.1:8888/counit/HelloWorld/?cocoon-view=write-source</code> will execute
      the tests up to the write-source step.</p>
<p> The testcases are executed within the transformations pipeline. Each test type (xslt and
      transformer) has its own match. Errors in this pipeline are caught and treated as test output.
      Custom CoUnit transformation test types should be added in the transformations pipeline.</p>
<div class="sect2" lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="mount-table"></a>mount-table</h3>
</div>
</div>
</div>
<p>The first step in the test pipeline is the mount-table matcher. In this step the uri
        part after "counit" is converted to the actual location of the application that has to be
        tested. After this step, the <code class="constant">{src}</code> pipeline parameter contains the
        location. </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="find-testsuite"></a>find-testsuite</h3>
</div>
</div>
</div>
<p> With the given location, the step find-testsuite will look for the testsuite.xml file,
        which should be located in the .counit directory at that location. It is also possible to
        tell this step to look into a subdirectory instead of the root directory. This is done by
        adding the path to the URL, like
        <code class="uri">http://127.0.0.1:8888/counit/HelloWorld/ByeWorld/</code>. The
        <code class="constant">HelloWorld</code> part is looked up in the counit mount-table and will be
        converted into a path (or result in an error message if the mount entry is not found). The
          <code class="constant">ByeWorld</code> part is treated as a subdirectory of this path. </p>
<p> The testcase.xml file can contain references to other testsuites. These will be
        included in this step. </p>
<p> It is can be desirable to execute only one test at a time, for example to test a failed
        testcase after fixing it. To execute one testcase in any of the found testsuite.xml files,
        add the testcase id to the path:
          <code class="uri">http://127.0.0.1:8888/counit/HelloWorld/ByeWorld/thefirsttestcase</code>. This will
        look for a testcase with id "thefirsttestcase" and execute that testcase only. The testcase
        doesn't necessarily have to be a testcase in the ByeWorld testsuite.xml, but can also be a
        testcase from a "mounted" testsuite.xml. A link to execute a testcase is automatically
        provided in the HTML output if a testcase fails. </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="prepare-xslt-stx"></a>prepare-xslt and prepare-stx</h3>
</div>
</div>
</div>
<p> These steps prepare the testcases which have defined an <code class="constant">xslt</code> or
          <code class="constant">stx</code> as the transformation to test. The preparation is in fact the
        brewing of a cinclude instruction, which will tell the cinclude transformer to call the
          <code class="constant">transform-with-ss</code> pipeline. This will be a complete POST request
        which does not use the internal cocoon:/ mechanism. This makes it possible to handle the
        errors and treat any error data as output. If the internal cocoon:/ mechanism would have
        been used, cocoon will present an ugly error page and stop the test pipeline. </p>
<p>
<a name="input-xml"></a>The XSL file to call and the input xml are included as POST parameters.
        The input xml can be passed by two ways: via the <code class="constant">@input</code> attribute on
        the <code class="constant">testcase</code> element, which contains a URI, which points to the
        location of an XML input document, or by the <code class="constant">input</code> element, which
        contains the XML directly. In the first case the called transform-with-ss pipeline will
        generate from the URI, in the latter case it will use the stream generator to read the XML
        from the request parameter.</p>
<p>Because the cinclude (and write-source) steps will be executed after this step, it is
        not possible to use cinclude or sourcewriting instructions in the input- or expected XML if
        these are included in the testsuite.xml document. These instructions would be executed by
        the following steps. Use the URI method for input if the input contains special instructions
        for cocoon components.</p>
<p>Any parameters that are defined in the xslt or stx element will be passed in the same
        request and will be passed through to the stylesheet transformation.</p>
<p>Instead of using a URI in the <code class="constant">src</code> attribute, a generated stylesheet
        can be used as well. In this case, don't include a <code class="constant">src</code> attribute and
        include two child elements in the <code class="constant">xslt</code> or <code class="constant">stx</code>
        element: an <code class="constant">input</code> element and a transformation element like xslt, stx
        or transformer. The input will be passed through the given transformation and should result
        in a generated stylesheet. </p>
<p>Generated stylesheets can be nested with no limits except the physical limits of your
        computer and your patience.</p>
<p>A generated stylesheet can not contain imports which have a relative URL as href
        attribute. In these cases you will receive a cryptic error message about the cocoon:
        protocol that is not recognized.</p>
</div>
<div class="sect2" lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="prepare-transformer"></a>prepare-transformer</h3>
</div>
</div>
</div>
<p> The prepare-transformer step prepares testcases which are meant to test a custom
        transformer, i.e. which have a <code class="constant">transformer</code> element. The preparation
        consists of two things. Firstly an instruction for the sourcewriting transformer is made up
        to generate a small sitemap which declares the transformer and calls it with the input xml.
        Secondly a cinclude instruction is prepared to call the do-transformation pipeline from the
        main sitemap. This pipeline will actually mount the newly generated sitemap. </p>
<p>The new sitemap will be generated in the CoUnit directory and will most likely have a
        unique name. In a following step the generated sitemap will be deleted again, but if the
        pipeline has been halted by using the cocoon-view parameter or by a fatal error, you might
        end up with garbage in the CoUnit directory.</p>
<p>The mechanism to include the input xml is the same as the previous step, see the
        information in <a href="#input-xml">prepare-xslt</a> about this.</p>
<p>If the transformer needs configuration, any parameters can be included in the
          <code class="constant">configuration</code> element which is a child element of
          <code class="constant">transformer</code>. These will be copied into the generated sitemap. Any
        run-time paramaters to the transformation can be included in the
        <code class="constant">parameters</code> element. These will be included into the generated sitemap
        as <code class="constant">map:parameter</code> elements.</p>
</div>
<div class="sect2" lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="new"></a>(new transformation test types)</h3>
</div>
</div>
</div>
<p> Any custom CoUnit transformation test types like <code class="constant">xslt</code> and
          <code class="constant">transformer</code> should be prepared with a stylesheet on this place in the
        testpipeline. The stylesheet should include cinclude elements to call the transformation
        with a full URL. </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="prepare-filter"></a>prepare-filter</h3>
</div>
</div>
</div>
<p> The <code class="constant">output-filter</code> instruction is interpreted by the prepare-filter
        step. This step writes a temporary stylesheet to disk if the built-in filter features are
        used. After that, it extends the cinclude instruction which triggers the transformation with
        a parameter which contains the URI to the stylesheet (generated or user-defined). The
        sitemap resource "post-testcase" will pick up this parameter and execute the stylesheet. Any
        user defined CoUnit transformation should include a call to post-testcase if the output
        should be filterable. </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="write-source"></a>write-source</h3>
</div>
</div>
</div>
<p>This step will execute the sourcewriting instructions that have been prepared by
        previous steps. After this step, the temporary sitemaps have been written to disk.</p>
</div>
<div class="sect2" lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="cinclude"></a>cinclude</h3>
</div>
</div>
</div>
<p>This step will execute the cinclude instructions that have been prepared by previous
        steps. In fact this means that this steps does the actual transformation, because the
        cinclude tags refer to the transformation pipeline. After this step the output of each
        transformation is included in the testcases in the <code class="constant">output</code>
      element.</p>
</div>
<div class="sect2" lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="cleanup"></a>prepare-cleanup and cleanup</h3>
</div>
</div>
</div>
<p> The prepare-cleanup step includes an instruction to the sourcewriting transformer to
        delete the generated sitemap. The cleanup step performs the deletion. </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="include-expected-output"></a>include-expected-output</h3>
</div>
</div>
</div>
<p> The step include-expected-output is only necessary for testcases that don't contain an
          <code class="constant">expect</code> element, but use the <code class="constant">@expect</code> attribute
        that contains an URI. This step creates a new <code class="constant">expect</code> element and
        includes the XML from the given URI in this element.</p>
</div>
<div class="sect2" lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="remove-whitespace"></a>remove-whitespace</h3>
</div>
</div>
</div>
<p>It can be very annoying to make sure the expect element resembles the exact output of
        the transformation if the output contains unexpected whitespace or leaves out whitespace
        where you would expect it. To circumvent this, any whitespace is normalized by default. If
        this gives unwanted side-effects, the <code class="constant">@ignore-whitespace</code> attribute on
        the testcase can be used. This step normalizes whitespace from any text() node if the
        attribute is NOT set to <code class="constant">false</code>.</p>
</div>
<div class="sect2" lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="evaluate-results"></a>evaluate-results</h3>
</div>
</div>
</div>
<p>Evalue-results compares the contents of the <code class="constant">expect</code> element with the
        contents of the <code class="constant">output</code> element (see <a href="#cinclude" title="cinclude">cinclude</a>). This is done by using the xsltunit 0.2 library. The result of the
        comparison is added to the testcase.</p>
</div>
<div class="sect2" lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="format-results"></a>format-results</h3>
</div>
</div>
</div>
<p>This step removes the garbage from the output of all the preceding steps, and formats
        the results of the comparison to resemble the JUnit XML output.</p>
</div>
<div class="sect2" lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="html-report"></a>html-report (optional)</h3>
</div>
</div>
</div>
<p>If the report/** pipeline is used, the html-report step will be executed as the last
        step. This step formats the JUnit results and shows them to a nice HTML
      representation.</p>
</div>
</div>
</div>
</body>
</html>
